Inside Macintosh: QuickDraw GX Graphics /

Chapter 6 - Picture Shapes / Picture Shapes Reference

Functions / Getting and Setting Picture Geometries

GXGetPicture

You can use the GXGetPicture function to obtain references to the shapes contained in a picture and references to their overriding styles, inks, and transforms.

long GXGetPicture(gxShape source, gxShape shapes[], 
                  gxStyle styles[], gxInk inks[], 
                  gxTransform transforms[]);

source

A reference to the picture shape whose items you want to examine.

shapes

An array of shape references. On return, this array contains references to the shapes contained in the source picture.

styles

An array of references to style objects. On return, this array contains references to the overriding styles contained in the source picture.

inks

An array of references to ink objects. On return, this array contains references to the overriding inks contained in the source picture.

transforms

An array of references to transform objects. On return, this array contains references to the overriding transforms contained in the source picture.

function result

The total number of items in the source picture.

DESCRIPTION

If you provide arrays for the shapes, styles, inks, and transforms parameters, this function copies the references to shapes, styles, inks, and transforms from the picture's geometry into these arrays. However, you may provide nil for any of these parameters to indicate that you do not want to obtain the corresponding references.

Typically, you call this function twice. The first time you specify nil for all of the array parameters and use the function result to determine the number of picture items, which you can use to allocate arrays large enough to contain the shape, style, ink, and transform references. Then you call the function a second time to determine the actual references.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
inconsistent_parameters	(debugging version)
parameter_out_of_range	(debugging version)
index_is_less_than_one	(debugging version)
count_is_less_than_one	(debugging version)
cannot_set_item_shapes_to_nil	(debugging version)
cannot_use_original_item_shapes_when_growing_picture
	(debugging version)
Warnings
index_out_of_range
count_out_of_range
picture_expected	(debugging version)
shape_access_not_allowed	(debugging version)
picture_cannot_contain_itself	(debugging version)
cannot_dispose_locked_tag	(debugging version)
cannot_dispose_default_shape	(debugging version)
cannot_dispose_default_style	(debugging version)
cannot_dispose_default_ink	(debugging version)
cannot_dispose_default_transform	(debugging version)
cannot_dispose_default_colorProfile	(debugging version)

SEE ALSO

For information about picture items and their overriding styles, inks, and transforms, see "About Picture Shapes" beginning on page 6-3.

For an example using this function, see "Getting and Setting Picture Geometries" beginning on page 6-31.

To examine a subset of the items in a picture geometry, use the GXGetPictureParts function, which is described on page 6-63.

To replace the information in the geometry of a picture shape, use the GXSetPicture function, which is described in the next section.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help